Patrones de Entidades de Módulos de JavaScript: Una Inmersión Profunda en el Modelado de Objetos de Dominio

En el mundo del desarrollo de software, especialmente dentro del dinámico y en constante evolución ecosistema de JavaScript, a menudo priorizamos la velocidad, los frameworks y las funcionalidades. Construimos interfaces de usuario complejas, nos conectamos a innumerables APIs e implementamos aplicaciones a un ritmo vertiginoso. Pero en esta prisa, a veces descuidamos el núcleo mismo de nuestra aplicación: el dominio del negocio. Esto puede llevar a lo que a menudo se llama la "Gran Bola de Barro", un sistema donde la lógica de negocio está dispersa, los datos no están estructurados y hacer un simple cambio puede desencadenar una cascada de errores imprevistos.

Aquí es donde entra en juego el Modelado de Objetos de Dominio. Es la práctica de crear un modelo rico y expresivo del espacio del problema en el que estás trabajando. Y en JavaScript, el Patrón de Entidad de Módulo es una forma poderosa, elegante y agnóstica del framework para lograr esto. Esta guía completa te guiará a través de la teoría, la práctica y los beneficios de este patrón, permitiéndote construir aplicaciones más robustas, escalables y mantenibles.

¿Qué es el Modelado de Objetos de Dominio?

Antes de sumergirnos en el patrón en sí, aclaremos nuestros términos. Es crucial distinguir este concepto del Modelo de Objetos del Documento (DOM) del navegador.

• Dominio: En software, el 'dominio' es el área temática específica a la que pertenece el negocio del usuario. Para una aplicación de comercio electrónico, el dominio incluye conceptos como Productos, Clientes, Pedidos y Pagos. Para una plataforma de redes sociales, incluye Usuarios, Publicaciones, Comentarios y Me Gusta.
• Modelado de Objetos de Dominio: Este es el proceso de crear un modelo de software que representa las entidades, sus comportamientos y sus relaciones dentro de ese dominio de negocio. Se trata de traducir conceptos del mundo real en código.

Un buen modelo de dominio no es solo una colección de contenedores de datos. Es una representación viva de las reglas de tu negocio. Un objeto Pedido no solo debe contener una lista de artículos; debe saber cómo calcular su total, cómo agregar un nuevo artículo y si se puede cancelar. Esta encapsulación de datos y comportamiento es la clave para construir un núcleo de aplicación resiliente.

El Problema Común: Anarquía en la Capa de "Modelo"

En muchas aplicaciones de JavaScript, especialmente aquellas que crecen orgánicamente, la capa de 'modelo' suele ser una ocurrencia tardía. Frecuentemente vemos este antipatrón:

            
// En algún lugar de un controlador o servicio de API...
async function createUser(req, res) {
  const { email, password, firstName, lastName } = req.body;

  // La lógica de negocio y la validación están dispersas aquí
  if (!email || !email.includes('@')) {
    return res.status(400).send({ error: 'Se requiere un correo electrónico válido.' });
  }

  if (!password || password.length < 8) {
    return res.status(400).send({ error: 'La contraseña debe tener al menos 8 caracteres.' });
  }

  const user = {
    email: email.toLowerCase(),
    password: await hashPassword(password), // Alguna función de utilidad
    fullName: `${firstName} ${lastName}`, // La lógica para los datos derivados está aquí
    createdAt: new Date()
  };

  // Ahora, ¿qué es `user`? Es solo un objeto plano.
  // Nada impide que otro desarrollador haga esto más tarde:
  // user.email = 'un-correo-electrónico-inválido';
  // user.password = 'corto';

  await db.users.insert(user);
  res.status(201).send(user);
}

            

              
                Copy
              
            
          

Este enfoque presenta varios problemas críticos:

• Sin una Única Fuente de Verdad: Las reglas para lo que constituye un 'usuario' válido se definen dentro de este controlador. ¿Qué pasa si otra parte del sistema necesita crear un usuario? ¿Copias y pegas la lógica? Esto conduce a la inconsistencia y a los errores.
• Modelo de Dominio Anémico: El objeto `user` es solo una bolsa de datos 'tonta'. No tiene comportamiento ni autoconciencia. Toda la lógica que opera sobre él vive externamente.
• Baja Cohesión: La lógica para crear el nombre completo de un usuario se mezcla con el manejo de la solicitud/respuesta de la API y el hashing de la contraseña.
• Difícil de Probar: Para probar la lógica de creación de usuarios, tienes que simular las solicitudes y respuestas HTTP, las bases de datos y las funciones de hashing. No puedes simplemente probar el concepto de 'usuario' de forma aislada.
• Contratos Implícitos: El resto de la aplicación solo tiene que 'asumir' que cualquier objeto que represente a un usuario tiene una cierta forma y que sus datos son válidos. No hay garantías.

La Solución: El Patrón de Entidad de Módulo de JavaScript

El Patrón de Entidad de Módulo aborda estos problemas mediante el uso de un módulo estándar de JavaScript (un archivo) para definir todo acerca de un solo concepto de dominio. Este módulo se convierte en la fuente definitiva de verdad para esa entidad.

Una Entidad de Módulo normalmente expone una función de fábrica. Esta función es responsable de crear una instancia válida de la entidad. El objeto que devuelve no es solo datos; es un objeto de dominio rico que encapsula sus propios datos, validación y lógica de negocio.

Características Clave de una Entidad de Módulo

• Encapsulación: Agrupa los datos y las funciones que operan sobre esos datos.
• Validación en el Límite: Asegura que sea imposible crear una entidad inválida. Protege su propio estado.
• API Clara: Expone un conjunto limpio e intencional de funciones (una API pública) para interactuar con la entidad, al tiempo que oculta los detalles internos de la implementación.
• Inmutabilidad: A menudo produce objetos inmutables o de solo lectura para evitar cambios de estado accidentales y asegurar un comportamiento predecible.
• Portabilidad: No tiene dependencias de frameworks (como Express, React) o sistemas externos (como bases de datos, APIs). Es pura lógica de negocio.

Componentes Centrales de una Entidad de Módulo

Reconstruyamos nuestro concepto de `User` usando este patrón. Crearemos un archivo, `user.js` (o `user.ts` para los usuarios de TypeScript), y lo construiremos paso a paso.

1. La Función de Fábrica: Tu Constructor de Objetos

En lugar de clases, usaremos una función de fábrica (por ejemplo, `buildUser`). Las fábricas ofrecen una gran flexibilidad, evitan luchar con la palabra clave `this` y hacen que el estado privado y la encapsulación sean más naturales en JavaScript.

Nuestro objetivo es crear una función que tome datos sin procesar y devuelva un objeto Usuario bien formado y confiable.

            
// archivo: /domain/user.js

export default function buildMakeUser() {
  // Esta función interna es la fábrica real.
  // Tiene acceso a cualquier dependencia pasada a buildMakeUser, si es necesario.
  return function makeUser({
    id = generateId(), // Asumamos una función para generar un ID único
    firstName,
    lastName,
    email,
    passwordHash,
    createdAt = new Date()
  }) {
    // ... la validación y la lógica irán aquí ...

    const user = {
      getId: () => id,
      getFirstName: () => firstName,
      getLastName: () => lastName,
      getEmail: () => email,
      getPasswordHash: () => passwordHash,
      getCreatedAt: () => createdAt
    };

    // Usando Object.freeze para hacer el objeto inmutable.
    return Object.freeze(user);
  }
}

            

              
                Copy
              
            
          

Observa algunas cosas aquí. Estamos usando una función que devuelve una función (una función de orden superior). Este es un patrón poderoso para inyectar dependencias, como un generador de ID únicos o una biblioteca de validación, sin acoplar la entidad a una implementación específica. Por ahora, lo mantendremos simple.

2. Validación de Datos: El Guardián en la Puerta

Una entidad debe proteger su propia integridad. Debería ser imposible crear un `User` en un estado inválido. Agregamos la validación justo dentro de la función de fábrica. Si los datos no son válidos, la fábrica debería lanzar un error, indicando claramente lo que está mal.

            
// archivo: /domain/user.js

export default function buildMakeUser({ Id, isValidEmail, hashPassword }) {
  return function makeUser({
    id = Id.makeId(),
    firstName,
    lastName,
    email,
    password, // Ahora tomamos una contraseña simple y la manejamos dentro
    createdAt = new Date()
  }) {
    if (!Id.isValidId(id)) {
      throw new Error('El usuario debe tener un id válido.');
    }
    if (!firstName || firstName.length < 2) {
      throw new Error('El nombre debe tener al menos 2 caracteres.');
    }
    if (!lastName || lastName.length < 2) {
      throw new Error('El apellido debe tener al menos 2 caracteres.');
    }
    if (!email || !isValidEmail(email)) {
      throw new Error('El usuario debe tener una dirección de correo electrónico válida.');
    }
    if (!password || password.length < 8) {
      throw new Error('La contraseña debe tener al menos 8 caracteres.');
    }

    // La normalización y la transformación de los datos ocurren aquí
    const passwordHash = hashPassword(password); 
    const normalizedEmail = email.toLowerCase();

    return Object.freeze({
      getId: () => id,
      getFirstName: () => firstName,
      getLastName: () => lastName,
      getEmail: () => normalizedEmail,
      getPasswordHash: () => passwordHash,
      getCreatedAt: () => createdAt
    });
  }
}

            

              
                Copy
              
            
          

Ahora, cualquier parte de nuestro sistema que quiera crear un `User` debe pasar por esta fábrica. Obtenemos una validación garantizada cada vez. También hemos encapsulado la lógica de hashing de la contraseña y la normalización de la dirección de correo electrónico. El resto de la aplicación no necesita saber ni preocuparse por estos detalles.

3. Lógica de Negocio: Encapsulando el Comportamiento

Nuestro objeto `User` todavía es un poco anémico. Contiene datos, pero no *hace* nada. Agreguemos comportamiento: métodos que representen acciones específicas del dominio.

            
// ... dentro de la función makeUser ...

    if (!password || password.length < 8) {
      // ...
    }

    const passwordHash = hashPassword(password);
    const normalizedEmail = email.toLowerCase();

    return Object.freeze({
      getId: () => id,
      getFirstName: () => firstName,
      getLastName: () => lastName,
      getEmail: () => normalizedEmail,
      getPasswordHash: () => passwordHash,
      getCreatedAt: () => createdAt,

      // Lógica de Negocio / Comportamiento
      getFullName: () => `${firstName} ${lastName}`,
      
      // Un método que describe una regla de negocio
      canVote: () => {
          // En algunos países, la edad para votar es de 18 años. Esta es una regla de negocio.
          // Asumamos que tenemos una propiedad dateOfBirth.
          const age = calculateAge(dateOfBirth);
          return age >= 18;
      }
    });
// ...

            

              
                Copy
              
            
          

La lógica de `getFullName` ya no está dispersa en algún controlador aleatorio; pertenece a la propia entidad `User`. Cualquiera que tenga un objeto `User` ahora puede obtener de forma confiable el nombre completo llamando a `user.getFullName()`. La lógica se define una vez, en un solo lugar.

Construyendo un Ejemplo Práctico: Un Sistema Simple de Comercio Electrónico

Apliquemos este patrón a un dominio más interconectado. Modelaremos un `Product`, un `OrderItem` y un `Order`.

1. Modelando la Entidad `Product`

Un producto tiene un nombre, un precio y alguna información de stock. Debe tener un nombre y su precio no puede ser negativo.

            
// archivo: /domain/product.js

export default function buildMakeProduct({ Id }) {
  return function makeProduct({
    id = Id.makeId(),
    name,
    description,
    price,
    stock = 0
  }) {
    if (!Id.isValidId(id)) {
      throw new Error('El producto debe tener un ID válido.');
    }
    if (!name || name.trim().length < 2) {
      throw new Error('El nombre del producto debe tener al menos 2 caracteres.');
    }
    if (isNaN(price) || price <= 0) {
      throw new Error('El producto debe tener un precio mayor que cero.');
    }
    if (isNaN(stock) || stock < 0) {
      throw new Error('El stock debe ser un número no negativo.');
    }

    return Object.freeze({
      getId: () => id,
      getName: () => name,
      getDescription: () => description,
      getPrice: () => price,
      getStock: () => stock,
      
      // Lógica de negocio
      isAvailable: () => stock > 0,
      
      // Un método que modifica el estado devolviendo una nueva instancia
      reduceStock: (amount) => {
        if (amount > stock) {
          throw new Error('No hay suficiente stock disponible.');
        }
        // Devuelve un NUEVO objeto product con el stock actualizado
        return makeProduct({ id, name, description, price, stock: stock - amount });
      }
    });
  }
}

            

              
                Copy
              
            
          

Observa el método `reduceStock`. Este es un concepto crucial relacionado con la inmutabilidad. En lugar de cambiar la propiedad `stock` en el objeto existente, devuelve una *nueva* instancia de `Product` con el valor actualizado. Esto hace que los cambios de estado sean explícitos y predecibles.

2. Modelando la Entidad `Order` (La Raíz Agregada)

Un `Order` es más complejo. Es lo que el Diseño Dirigido por el Dominio (DDD) llama una "Raíz Agregada". Es una entidad que administra otros objetos más pequeños dentro de su límite. Un `Order` contiene una lista de `OrderItem`s. No agregas un producto directamente a un pedido; agregas un `OrderItem` que contiene un producto y una cantidad.

            
// archivo: /domain/order.js

export const ORDER_STATUS = {
  PENDING: 'PENDING',
  PAID: 'PAID',
  SHIPPED: 'SHIPPED',
  CANCELLED: 'CANCELLED'
};

export default function buildMakeOrder({ Id, validateOrderItem }) {
  return function makeOrder({
    id = Id.makeId(),
    customerId,
    items = [],
    status = ORDER_STATUS.PENDING,
    createdAt = new Date()
  }) {
    if (!Id.isValidId(id)) {
      throw new Error('El pedido debe tener un ID válido.');
    }
    if (!customerId) {
      throw new Error('El pedido debe tener un ID de cliente.');
    }

    let orderItems = [...items]; // Crea una copia privada para administrar

    return Object.freeze({
      getId: () => id,
      getCustomerId: () => customerId,
      getItems: () => [...orderItems], // Devuelve una copia para evitar la modificación externa
      getStatus: () => status,
      getCreatedAt: () => createdAt,
      
      // Lógica de Negocio
      calculateTotal: () => {
        return orderItems.reduce((total, item) => {
          return total + (item.getPrice() * item.getQuantity());
        }, 0);
      },

      addItem: (item) => {
        // validateOrderItem es una función que asegura que el artículo sea una entidad OrderItem válida
        validateOrderItem(item);

        // Regla de negocio: evitar agregar duplicados, solo aumentar la cantidad
        const existingItemIndex = orderItems.findIndex(i => i.getProductId() === item.getProductId());

        if (existingItemIndex > -1) {
          const newQuantity = orderItems[existingItemIndex].getQuantity() + item.getQuantity();
          // Aquí actualizarías la cantidad en el artículo existente
          // (Esto requiere que los artículos sean mutables o que tengan un método de actualización)
        } else {
          orderItems.push(item);
        }
      },

      markPaid: () => {
        if (status !== ORDER_STATUS.PENDING) {
          throw new Error('Solo los pedidos pendientes pueden marcarse como pagados.');
        }
        // Devuelve una nueva instancia de Order con el estado actualizado
        return makeOrder({ id, customerId, items: orderItems, status: ORDER_STATUS.PAID, createdAt });
      }
    });
  }
}

            

              
                Copy
              
            
          

Esta entidad `Order` ahora aplica reglas de negocio complejas:

• Administra su propia lista de artículos.
• Sabe cómo calcular su propio total.
• Aplica transiciones de estado (por ejemplo, solo puedes marcar un pedido `PENDING` como `PAID`).

La lógica de negocio para los pedidos ahora está perfectamente encapsulada dentro de este módulo, se puede probar de forma aislada y se puede reutilizar en toda la aplicación.

Patrones Avanzados y Consideraciones

Inmutabilidad: La Piedra Angular de la Predictibilidad

Hemos tocado la inmutabilidad. ¿Por qué es tan importante? Cuando los objetos son inmutables, puedes pasarlos por toda tu aplicación sin temor a que alguna función distante cambie su estado inesperadamente. Esto elimina toda una clase de errores y hace que el flujo de datos de tu aplicación sea mucho más fácil de razonar.

Object.freeze() proporciona una congelación superficial. Para las entidades con objetos o arreglos anidados (como nuestro `Order`), debes ser más cuidadoso. Por ejemplo, en `order.getItems()`, devolvimos una copia (`[...orderItems]`) para evitar que la persona que llama insertara elementos directamente en el arreglo interno del pedido.

Para aplicaciones complejas, bibliotecas como Immer pueden facilitar mucho el trabajo con estructuras anidadas inmutables, pero el principio central sigue siendo: trata tus entidades como valores inmutables. Cuando sea necesario realizar un cambio, crea un nuevo valor.

Manejo de Operaciones Asíncronas y Persistencia

Es posible que hayas notado que nuestras entidades son completamente síncronas. No saben nada sobre bases de datos o APIs. ¡Esto es intencional y una gran fortaleza del patrón!

Las entidades no deben guardarse a sí mismas. El trabajo de una entidad es hacer cumplir las reglas de negocio. El trabajo de guardar datos en una base de datos pertenece a una capa diferente de tu aplicación, a menudo llamada Capa de Servicio, Capa de Caso de Uso o Patrón de Repositorio.

Así es como interactúan:

            
// archivo: /use-cases/create-user.js

// Este caso de uso depende de la fábrica de entidades de usuario y de una función de acceso a la base de datos.
export default function makeCreateUser({ makeUser, usersDatabase }) {
  return async function createUser(userInfo) {
    // 1. Crea una entidad de dominio válida. Este paso valida los datos.
    const user = makeUser(userInfo);

    // 2. Verifica si hay reglas de negocio que requieran datos externos (por ejemplo, la unicidad del correo electrónico)
    const exists = await usersDatabase.findByEmail({ email: user.getEmail() });
    if (exists) {
      throw new Error('La dirección de correo electrónico ya está en uso.');
    }

    // 3. Persiste la entidad. La base de datos necesita un objeto plano.
    const persisted = await usersDatabase.insert({
      id: user.getId(),
      firstName: user.getFirstName(),
      // ... y así sucesivamente
    });

    return persisted;
  }
}

            

              
                Copy
              
            
          

Esta separación de responsabilidades es poderosa:

• La entidad `User` es pura, síncrona y fácil de probar unitariamente.
• El caso de uso `createUser` es responsable de la orquestación y se puede probar la integración con una base de datos simulada.
• El módulo `usersDatabase` es responsable de la tecnología de base de datos específica y se puede probar por separado.

Serialización y Deserialización

Tus entidades, con sus métodos, son objetos enriquecidos. Pero cuando envías datos a través de una red (por ejemplo, en una respuesta de API JSON) o los almacenas en una base de datos, necesitas una representación de datos simple. Este proceso se llama serialización.

Un patrón común es agregar un método `toJSON()` o `toObject()` a tu entidad.

            
// ... dentro de la función makeUser ...

    return Object.freeze({
      getId: () => id,
      // ... otros getters

      // Método de serialización
      toObject: () => ({
        id,
        firstName,
        lastName,
        email: normalizedEmail,
        createdAt
        // Observa que no incluimos el passwordHash
      })
    });

            

              
                Copy
              
            
          

El proceso inverso, tomar datos planos de una base de datos o API y convertirlos nuevamente en una entidad de dominio enriquecida, es exactamente para lo que sirve tu función de fábrica `makeUser`. Esto es deserialización.

Tipado con TypeScript o JSDoc

Si bien este patrón funciona perfectamente en JavaScript vainilla, agregar tipos estáticos con TypeScript o JSDoc lo sobrecarga. Los tipos te permiten definir formalmente la 'forma' de tu entidad, proporcionando una excelente autocompletación y comprobaciones en tiempo de compilación.

            
// archivo: /domain/user.ts

// Define la interfaz pública de la entidad
export type User = Readonly<{
  getId: () => string;
  getFirstName: () => string;
  // ... etc
  getFullName: () => string;
}>;

// La función de fábrica ahora devuelve el tipo User
export default function buildMakeUser(...) {
  return function makeUser(...): User {
    // ... implementación
  }
}

            

              
                Copy
              
            
          

Los Beneficios Generales del Patrón de Entidad de Módulo

Al adoptar este patrón, obtienes una multitud de beneficios que se acumulan a medida que crece tu aplicación:

• Única Fuente de Verdad: Las reglas de negocio y la validación de datos están centralizadas y no son ambiguas. Un cambio en una regla se realiza en exactamente un lugar.
• Alta Cohesión, Bajo Acoplamiento: Las entidades son autónomas y no dependen de sistemas externos. Esto hace que tu código base sea modular y fácil de refactorizar.
• Máxima Capacidad de Prueba: Puedes escribir pruebas unitarias simples y rápidas para tu lógica de negocio más crítica sin simular el mundo entero.
• Experiencia del Desarrollador Mejorada: Cuando un desarrollador necesita trabajar con un `User`, tiene una API clara, predecible y auto-documentada para usar. No más adivinar la forma de los objetos planos.
• Una Base para la Escalabilidad: Este patrón te brinda un núcleo estable y confiable. A medida que agregas más características, frameworks o componentes de UI, tu lógica de negocio permanece protegida y consistente.

Conclusión: Construye un Núcleo Sólido para Tu Aplicación

En un mundo de frameworks y bibliotecas de rápido movimiento, es fácil olvidar que estas herramientas son transitorias. Cambiarán. Lo que perdura es la lógica central de tu dominio de negocio. Invertir tiempo en modelar adecuadamente este dominio no es solo un ejercicio académico; es una de las inversiones a largo plazo más significativas que puedes hacer en la salud y la longevidad de tu software.

El Patrón de Entidad de Módulo de JavaScript proporciona una forma simple, poderosa y nativa de implementar estas ideas. No requiere un framework pesado o una configuración compleja. Aprovecha las características fundamentales del lenguaje (módulos, funciones y cierres) para ayudarte a construir un núcleo limpio, resiliente y comprensible para tu aplicación. Comienza con una entidad clave en tu próximo proyecto. Modela sus propiedades, valida su creación y dale comportamiento. Estarás dando el primer paso hacia una arquitectura de software más robusta y profesional.